<html>
<body>
<h1>Script Plugin</h1>
<p>The Script plugin allows ad hoc targets to be written in scripting languages such as Javascript.</p>
<div id="content-before">
<p>Built-in and optional Ant tasks may be used, in addition to any Quokka template targets.</p>
</div>
<div id="after-summary">
    <p>To use Ant optional tasks, it is necessary to add the required libraries to the
    <tt>ant-types</tt> project path. In general, only the dependency from Ant is required
    and all other dependencies will be included automatically. e.g. To use the <tt>ftp</tt>
    task, add the <tt>commons-net</tt> dependency from the <tt>apache.ant</tt> group and
    the <tt>commons.net</tt> library will be included automatically.</p>

    <p>To use a Quokka template target, you must declare the plugin as a dependency and
    declare the templates you're using via the <tt>templates</tt> attribute. You can
    then define properties and call <tt>quokka.execute</tt> to run the template instance.</p>
    
    <p>The following example shows how to run a javascript script that a uses built-in ant task,
    and optional ant task and a quokka plugin template.</p>
    <pre>&lt;dependency group="apache.ant" name="commons-net" version="1.7.1" paths="ant-types"/&gt;
&lt;plugin group="quokka.plugin.fop" version="?" templates="transform"/&gt;

&lt;plugin group="quokka.plugin.script" version="?"&gt;
    &lt;target name="myscript" template="javascript"&gt;
        &lt;property name="script"&gt;&lt;![CDATA[
          // Example of built-in tasks (echo)
          for (i=1; i&lt;=10; i++) {
            echo = project.createTask("echo");
            echo.setMessage(i*i);
            echo.perform();
          }

          // Example of optional Ant task (ftp) - dependencies are added to ant-types
          ftp = project.createTask("ftp")
          ftp.setUserid("ftp.crap.com")

          // Example of using a a quokka plugin (fop) - the plugin and template must be declared                
          props = new java.util.Properties()
          props.put("in","src/fop/fo.xml")
          props.put("out","${q.project.targetDir}/fop/fo.pdf")
          quokka.execute("quokka.plugin.fop", "transform", props)
        ]]&gt;&lt;/property&gt;
    &lt;/target&gt;
&lt;/plugin&gt;</pre>
    <p>The implementation uses Ant's standard scripting mechanism, so see Ant's <a href="http://ant.apache.org/manual/OptionalTasks/script.html">script task</a>
    for more information on accessing Ant types and tasks from a script.</p>
</div>
<div id="script">
    <p><b>Properties:</b></p>
    <ul>
        <li><b>language</b>: <i>Mandatory.</i> The programming language the script is written in. Must be a supported Apache BSF or JSR 223 language</li>
        <li><b>manager</b>: <i>Optional.</i> This can have one of three values (<tt>auto</tt>, <tt>bsf</tt> or <tt>javax</tt>). The default value is <tt>auto</tt>.
            <ul>
                <li><tt>bsf:</tt> use the BSF scripting manager to run the language.<br/>
                    <tt>javax:</tt> use the javax.scripting manager to run the language. (This will only work for JDK6 and higher).<br/>
                    <tt>auto:</tt> use the BSF engine if it exists, otherwise use the javax.scripting manager.
                </li>
            </ul>
        </li>
        <li><b>src</b>: <i>Optional.</i> The location of the script as a file, if not inline</li>
        <li><b>setBeans</b>: <i>Optional.</i> This attribute controls whether to set variables for all properties, references and targets in the running script. If this attribute is false, only the "project" and "quokka" variables are set. If this attribute is true all the variables are set. The default value of this attribute is "true"</li>
        <li><b>scriptClasspath</b>: <i>Optional.</i> Although strictly speaking it is optional, it is always
        required unless you're are running with a scripting language bundled with the JDK (at present, that's
            Javascript on JDK1.6+ on Linux, Windows and Solaris). The value should contain the paths that
            contain the necessary libraries to run the script. These include languages supported by Apache BSF,
            or JSR 223. The paths should be a comma separated list
        project and plugin paths that have a prefix of "project." and "plugin." respectively. See the javascript
        target below for an example.</li>
        <li><b>classpath</b>: <i>Optional.</i>A comma separated list of paths for libraries you want to
        use within your script. Project paths should be prefixed with "project."</li>
    </ul>
</div>
<div id="javascript">
    <p>The Javascript template is essentially the same as the script target, just pre-configured for Javascript.
    As such, all the the script properties above apply. Through the use of automatic profiles it will attempt to
    select Javascript libraries need for your platform and JDK version (BSF and rhino for JDKs prior to 1.6, JSR 223
    and rhino for 1.6 for OS X as it's not bundled, and nothing for other 1.6 platforms as it is bundled)</p>
</div>
</body>
</html>